package org.bhf.providers.ccache;

/**
 * Copyright (c) 2007, Blue Hole Software. All rights reserved.
 * Code licensed under the Apache 2.0 License:
 * http://www.apache.org/licenses/
 */

/**
 * Cache component state server side. An application should be able to run, albiet slowly, with the cache disabled.
 * You should test your application with the cache size limite set to 0!
 */
public interface ComponentStateCache
{
    /**
     * Recall a Component from cache.
     *
     * @param ID ID of the component
     * @param clazz Class name to qualify the ID
     * @param version Must not be null. We use a string form here because the key is a string and the version comes
     *  in as a string in the URL
     * @return null if the Component cannot be found
     */
    Object      recallComponent( final String clazz, final long ID, final int version );

    /**
     * Remember a Component for possible later retrieval.
     *
     * @param ID ID of the component
     * @param clazz Class name to qualify the ID
     * @param version state version of the component
     * @param component Must not be null
     */
    void        rememberComponent( final String clazz, final long ID, final int version, final Object component );

    /**
     * Set the size limit, in number of <code>Component</code>s, of the cache. The default is 1024.
     *
     * @param sizeLimit Maximum number of <code>Component</code>s to cache.
     */
    void        setLimit( int sizeLimit );

    /**
     * Get the size limit, in number of <code>Component</code>s, of the cache.
     *
     * @return sizeLimit Maximum number of <code>Component</code>s to cache.
     */
    int         getLimit();

    /**
     * Clear the cache of all <code>Component</code>s.
     */
    void        clear();
}
